PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/basic/qbtiny.exe/QBTINY.DOC

Text File | 1992-11-19 | 17.2 KB | 480 lines

                      The QBTiny Library                 page 1
                    =--------------------=
                          Version 1.2

       QBTiny  Copyright (c) 1992  Thomas G. Hanlin III



The QBTiny library replaces the default runtime library for
QuickBasic 4.x and PDS 7.x compilers. Using it can reduce the
size of your compiled programs to 20% of their original size.

QBTiny does not support floating point math, event trapping, or
several other BASIC features.  The differences between QBTiny
and the default support library are discussed in this manual.

The QBTiny collection is copyrighted and may be distributed
only according to the following rule:

   All QBTiny files must be distributed together as a unit in
   unmodified form.  No files may be left out or added.

You use QBTiny at your own risk.  It has been tested by me on
my own computers, but I will not assume any responsibility for
any problems it may cause you.  QBTiny is a complex library.
IT QUITE PROBABLY HAS SOME BUGS.  If you need a stable library
that has undergone real-life testing by thousands of people,
buy Crescent's P.D.Q.  See PDQINFO.TXT for details.

The QBTiny library may be used as-is.  It can no longer be
registered.  If you find the capabilities of QBTiny useful, you
are sure to be pleased with Crescent Software's P.D.Q., which
is a similar but more powerful product.  Besides making your
programs smaller, P.D.Q. lets you make TSRs and provides other
new capabilities for Microsoft BASIC compilers.

This manual always refers to the default support library as
BCOM45.LIB, which is for QuickBasic 4.5.  If you are using a
different compiler, you will have a different support library:
  BCOM40.LIB    QuickBasic 4.0 (early release)
  BCOM41.LIB    QuickBasic 4.0 (later release)
  BCL70ENR.LIB  PDS 7.0 (normal default)
  BCL71ENR.LIB  PDS 7.1 (normal default)
Substitute the appropriate library for BCOM45.LIB.  Likewise,
when I say QuickBasic, I am also referring to PDS.  If you need
support for Visual Basic for DOS, once again, Crescent's P.D.Q.
is the best solution.  QBTiny doesn't support VB-DOS.

                       Table of Contents                 page 2



 Overview and Legal Info ................................... 1

 What Is QBTiny? ........................................... 3

 How to Use QBTiny ......................................... 4

 Compatibility Issues ...................................... 5

 Statements Not Supported .................................. 9

 Crescent's P.D.Q. ........................................ 10

 Which Runtime? ........................................... 11

                       What Is QBTiny?                   page 3



Microsoft's QuickBasic compiler turns your BASIC source code
into an executable (.EXE) file.  It does this by converting the
source code into assembly language.  The simplest statements,
like A% = A% + 1, are converted directly to assembly language.
It would be inefficient to convert more complex statements
directly to assembly language, though, since it would cause a
lot of duplicated code.  Instead of entering complex statements
directly into assembly language, the compiler generates a call
to a standard library routine which takes care of the work.
Most BASIC commands have their own library routines.  For
example, the ASC function causes a call to a library routine
named B$FASC (an abbreviation for Basic Function ASC).  When
you compile a QuickBasic program to a stand-alone .EXE, it
normally uses the BCOM45.LIB library to supply the proper
support code.  The QBTINY.LIB library replaces this.

The first question that might pop into your mind is, why bother
with replacing the default library to begin with?  It's free
with the compiler and seems to work just fine as-is!

Well, the problem with the default library is that it was
developed over a period of many years by many people.  As you
might expect, this is not a particularly efficient way to make
a library-- there are routines in BCOM45.LIB which are never
even called any more!  The modularity of the routines is also
not at its best.  Now, QBTiny does not support all of the
routines that the default library does, but it was designed
over a period of months by a single expert assembly language
programmer.  This is why the simple program:

   PRINT "Hello, world!"

comes out to 12,308 bytes when linked with BCOM45, but only
2,658 bytes when linked with QBTiny.  Yep, the QBTiny version
is a mere 22% of the size of the BCOM45 version!  The more
complex MWORD demo (linked with my BasWiz and PBClone libraries
as well as QBTiny) comes out to 8,700 bytes with QBTiny, as
compared to 34,662 bytes when linked with BCOM45.  You won't
always get savings of this magnitude, but for most small to
medium programs the size difference is quite dramatic.

With a few exceptions that will be noted later on, you will not
take any performance penalties for using QBTiny instead of
BCOM45, either.  In fact, many QBTiny routines are faster than
the equivalent routines in the default support library.

QBTiny does not support all of the routines that the default
library does. In a few cases, it supports a routine, but not in
quite the same way.  These differences are discussed later.

                      How to Use QBTiny                  page 4



Before using QBTiny, you must compile your program from the
command line.  The /o switch is required to tell the compiler
to create an .OBJ that can become a stand-alone EXE file.  Few
of the other switches are compatible with QBTiny.  Compilation
goes like this:

   BC program/o;

That's the standard way of compiling from the command line--
nothing new there.  The differences come in at LINK time.
Instead of your old LINK syntax, which may have looked a bit
like this:

   LINK program/EX;

you would use a special syntax, like so:

   LINK program/NOD/EX,,NUL,QBTINY;

Note that the /EX (sometimes abbreviated /E, which isn't quite
safe) usually makes QuickBasic programs smaller.  LINK isn't
too bright, though, and will apply /EX whether or not it really
shrinks the program.  In the case of QBTiny, you'll sometimes
get better results by leaving the /EX off-- try it both ways to
be sure.  Most programs do benefit from the /EX switch.

If LINK reports "unresolved externals" errors, you are using
capabilities which QBTiny doesn't provide.  LINK will tell you
what routine names are missing.  Use SYMDEX to find out what
BASIC statement uses these routines.  If you're not sure where
in your program this BASIC statement is, try creating a pseudo
ASM listing-- BC.EXE will show you the code it generates in
assembly language form, more or less, if you ask politely:

   BC program/O/A,program,program;

This creates a program.LST file which will help you track down
where the problem lies.

                      Compatibility Issues               page 5



The QBTiny library is designed to mimic the default support
library as closely as possible.  However, it is still a work in
progress, and differences remain.  There are slight differences
in the handling of some individual routines and certain types
of routines are not yet supported at all.

QBTiny does not support floating point math.  It does not allow
single-precision or double-precision numbers or any routines
which require them.  It does not support event trapping-- no ON
COM, ON ERROR, ON KEY, ON PEN, ON STICK, ON STRIG, or ON
UEVENT.  It does not support dynamic arrays, READ/DATA, RANDOM
file mode, INPUT, or many graphics statements.

It will be wise to debug your programs with the default support
library before using QBTiny.  In the interest of efficiency,
QBTiny does little error checking on items that are assumed to
be within the control of the programmer.  For instance, QBTiny
will not know if you use an invalid display page with SCREEN.
However, it will report an error if there is a problem with
OPEN or PRINT#, for example.

Still with me?  That may have seemed like a lot, I know.  To
some extent, the reason Microsoft BASIC programs are so large
is because they try to do everything at once.  QBTiny provides
somewhat less capability as a trade-off for smaller files.
There are also new capabilities provided by QBTiny which
provide alternatives to the missing routines which are actually
more convenient than the originals.  For instance, although ON
ERROR isn't allowed, the ERR variable is still updated as you'd
expect.  You don't need slow and bulky error trapping to check
for errors with QBTiny!

You can also use the QBTiny library along with other libraries,
which can more than make up for any missing routines.  So you
can't use RANDOMIZE and RND?  No problem!  The RAND function in
my PBClone library is faster, smaller, and easier to use.

No need to search through your existing programs to figure out
whether they'll work with QBTiny as-is.  When you link them
with QBTiny, LINK itself will tell you which routines it was
expecting that are not provided by QBTiny.  The SYMDEX utility
(included) translates routine names to the names of the BASIC
statements to which they refer.  BASDEX converts the other way.
Between the two, you will be able to cross-reference BASIC
statements with their symbols. We'll get into more details on
that presently.  Right now, let's take a look at any individual
differences between QBTiny and the default support library.

                      Compatibility Issues               page 6



Graphics

The QBTiny graphics handler is unlike BCOM45 in a number of
respects.  It does not provide a simulated cursor, allow
graphics paging, or set a default palette on entering a mode.



Keyboard

If input is not redirected, keyboard handling is done through
BIOS calls.  The keyboard handler relies on 0000:0496h bit 4 to
tell it whether an enhanced keyboard driver is available.  This
may be incorrectly set on some old PC clones, making keyboard
input unavailable.  If you have this problem, please get in
touch, and I'll try to find a work-around for your machine.
This problem brought to you courtesy of Microsoft, which did
not see fit to provide DOS with enhanced keyboard support,
giving me no alternative but to go with direct machine access.



KILL

The QBTiny version of KILL does not support wildcards.



LINE

The QBTiny version of LINE does not support patterns in quite
the same way as QuickBASIC.  QuickBASIC always draws lines from
left to right, but does up and down according to the order of
the coordinates you give it.  QBTiny draws the line exactly
according to the order of the coordinates you give it.  In
addition, QuickBASIC uses a somewhat peculiar procedure for
handling patterns when drawing box frames, and ignores patterns
when drawing filled boxes.  QBTiny handles patterns for box
frames more the way you'd expect and supports patterns for
filled boxes.



LONG math

The QBTiny library does not support division or MOD for LONG
integers.  I couldn't think of a reasonably efficient way of
implementing 32-bit division on 16-bit processors.

                      Compatibility Issues               page 7



OPEN

The QBTiny version of OPEN does not support the RANDOM file
mode.  It does not support BASIC devices (COMn:, CONS:, KYBD:,
LPTn:, SCRN:).  However, DOS devices (AUX, COMn, CON, LPTn,
PRN) are supported.  Note that INPUT# and LINE INPUT# are not
available, so the INPUT file mode is rather limited.



PALETTE

The QBTiny version of PALETTE does not support the version of
PALETTE without parameters.



SETMEM

Since QBTiny only uses as much memory as it needs, unlike
BCOM45 (which allocates all base memory), the SETMEM function
has no real purpose in QBTiny.  Thus, the parameter passed to
SETMEM is meaningless and is ignored.



SWAP

The QBTiny version of SWAP does not allow you to swap normal
strings with other data types (such as fixed-length strings or
TYPEd variables).



TIMER

The BASIC function TIMER is designed to use floating point,
then convert the result to the appropriate numeric type.  The
QBTiny version has been modified to skip the floating point
handling, and only supports TIMER for long integers.

To make sure TIMER returns a long integer, you should enclose
it in CLNG unless it is returning the result directly to a
variable.  For example, these are ok:

   A& = TIMER
   PRINT CLNG(TIMER)

But not this, since the type isn't apparent (and is assumed to
be floating point):

   PRINT TIMER

                      Compatibility Issues               page 8



WIDTH

The QBTiny version of WIDTH supports 40 and 80 column modes. It
ignores attempts to change the number of rows, however.  While
it does support changing the width of open files, it does not
allow you to change the width of BASIC devices (QBTiny supports
only DOS devices, not BASIC devices).



VAL

The BASIC function VAL is designed to use floating point, then
convert the result to the appropriate numeric type.  The QBTiny
version has been modified to skip the floating point handling,
and only supports VAL for integers and longs.  One side effect
is that the QBTiny version won't always detect VAL overflows.

To make sure VAL returns an integer or long integer, you should
enclose it in CINT or CLNG unless it is returning the result
directly to a variable.  For example, these are ok:

   A% = VAL(St$)
   A% = CINT(VAL(St$)
   PRINT CINT(VAL(St$))

But not this, since the type isn't apparent (and is assumed to
be floating point):

   PRINT VAL(St$)

The QBTiny version of VAL does not mimic certain BASIC bugs
which appear with hex and octal numbers.  It won't gratuitously
sign-extend long integer hex and octal, either.  For example:

   Function              QBTiny Result     BASIC Result
   -------------        ---------------   -------------------
   VAL("&H")                   0                 203
   VAL("-&1")                  0          Type Mismatch Error
   CLNG(VAL("&HFFFF"))       65535                -1

                   Statements Not Supported              page 9



Floating point:

 ATN       CDBL      COS       CSNG      CVD       CVDMBF
 EXP       INT       FIX       LOG       MKD$      MKDMBF$
 MKS$      MKSMBF$   RANDOMIZE RND       SIN       SOUND
 SQR       TAN



Graphics:

 CIRCLE    GET       PAINT     PMAP      PUT       VIEW
 WINDOW



Event trapping:

 COM       KEY       PEN       PLAY      STRIG     TIMER
 UEVENT

 ON ERROR GOTO



Miscellaneous:

 CHAIN     CLEAR     DATA      DRAW      ENVIRON   ERASE
 ERDEV     ERDEV$    ERL       FIELD     FILES     INPUT
 INPUT#    IOCTL     IOCTL$    KEY ON    LINE INPUT#
 LOCK      LPRINT USING        PLAY      PRINT USING
 PRINT# USING        READ      REDIM     RESTORE   RESUME
 RUN       SHELL     TROFF     TRON      UNLOCK    VARPTR$



 DIM           (for $DYNAMIC arrays)
 OPEN          (for RANDOM)
 MOD or \ with LONG integers (only allowed with QBTINY3.LIB)
 Floating point math



PDS:

 CVC       EVENT     MKC$      PRESERVE  STACK

 Far strings
 Currency math
 ISAM support

                      Crescent's P.D.Q.                 page 10



Many of you are probably familiar with Crescent Software's
P.D.Q. library.  P.D.Q. is similar to QBTiny in that it is a
replacement for the default support library.  P.D.Q. provides
some powerful advantages which QBTiny does not have, including
the ability to make TSRs and interrupt handlers.  Crescent also
provides printed manuals, phone tech support, and support for
BASCOM/PDS as well as QuickBasic.  P.D.Q. runs about $150.
Crescent Software is available at the following:

   800-35-BASIC    orders only, voice line | 9:00-5:00 EST
   203-438-5300    tech info, voice line   | (Connecticut)
   203-426-5958    BBS, modem line         |

   Crescent Software, Inc.
   11 Bailey Avenue
   Ridgefield, CT 06877

As I write this, the best features of QBTiny are in the process
of being merged into P.D.Q.  In addition, P.D.Q. is being
updated to support Microsoft's new Visual Basic for DOS, which
is incompatible with QBTiny.  Call Crescent for the latest
details, and tell 'em Tom Hanlin sent you!

                        Which Runtime?                  page 11



It is possible for your program to automatically detect which
of the three runtime libraries (default, P.D.Q., QBTiny) it is
using.  Of course, the program is unlikely to compile if it
uses a feature that isn't provided by the specified library.
Still, since there are differences in the way each library
handles specific routines, it may be helpful to know which one
is being used.

The VAL function is implemented differently by each library.
The P.D.Q. version stops when it encounters a space.  The
QBTiny version does not mimic certain obscure bugs that are
present in the default library.  The following program fragment
makes use of these differences to identify which runtime
library is in use:

   IF CINT(VAL("1 2")) = 1 THEN   ' P.D.Q. stops at spaces
      PRINT "PDQ.LIB"
   ELSEIF CINT(VAL("&H")) THEN    ' BCOM45 has a hex bug
      PRINT "BCOM45.LIB"
   ELSE                           ' otherwise, must be QBTiny
      PRINT "QBTINY.LIB"
   END IF